NavTranslateFile

NavTranslateFile
Header:	Navigation.h		Carbon status:	Supported

Provides a means for files opened through Navigation Services to be read from different file formats.

OSErr NavTranslateFile (
    NavReplyRecord *reply, 
    NavTranslationOptions howToTranslate
);

reply: A pointer to a structure of type NavReplyRecord. Upon return, Navigation Services uses this structure to provide translation information about the selected files.
howToTranslate: A value of type NavTranslationOptions. Pass one of these constants to tell Navigation Services how to perform the translation: either in-place or by making a copy of the file. For a description of the constants, see “Translation Option Constants”.

function result: A result code.

DISCUSSION

Under automatic file translation, Navigation Services calls the NavTranslateFile function as necessary before returning from a file-opening function.

Your application can perform its own translation using the NavReplyRecord structure you specified in the translateInfo parameter. The NavReplyRecord structure contains a list of descriptors for the file or files to be opened and a corresponding list of translation specification records that can be passed to the Translation Manager. To determine if your application has to translate a file, your application can examine the NavReplyRecord structure to see if Navigation Services set the translationNeeded field to true. (The translationNeeded field of the NavReplyRecord structure is also set to true after returning from a NavGetFile call during which automatic translation was performed.) If you want to turn off automatic file translation, set the constant kNavDontAutoTranslate in the dialogOptionFlags field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the file-opening function.

If your application uses the NavTranslateFile function after opening a file without automatic translation, Navigation Services checks to see if the source location can accept a new file. If the source location is not available (as occurs when the volume is locked or there is insufficient space), Navigation Services prompts the user to select a location in which to save the translated file. The same prompt may occur when automatic translation is enabled in an Open dialog box.

For more information, see “Translating Files on Open”.

VERSION NOTES

Available in Navigation Services 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when NavigationLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by NavigationLib 1.0 and later.